---
title: Webhook
description: Receive webhooks from any service by configuring a custom webhook.
---

import { BlockInfoCard } from "@/components/ui/block-info-card"

<BlockInfoCard 
  type="generic_webhook"
  color="#10B981"
  icon={true}
  iconSvg={`<svg className="block-icon"
      
      fill='currentColor'
      
      
      viewBox='0 0 24 24'
      xmlns='http://www.w3.org/2000/svg'
    >
      <path d='M17.974 7A4.967 4.967 0 0 0 18 6.5a5.5 5.5 0 1 0-8.672 4.491L7.18 15.114A2.428 2.428 0 0 0 6.496 15 2.5 2.5 0 1 0 9 17.496a2.36 2.36 0 0 0-.93-1.925l2.576-4.943-.41-.241A4.5 4.5 0 1 1 17 6.5a4.8 4.8 0 0 1-.022.452zM6.503 18.999a1.5 1.5 0 1 1 1.496-1.503A1.518 1.518 0 0 1 6.503 19zM18.5 12a5.735 5.735 0 0 0-1.453.157l-2.744-3.941A2.414 2.414 0 0 0 15 6.5a2.544 2.544 0 1 0-1.518 2.284l3.17 4.557.36-.13A4.267 4.267 0 0 1 18.5 13a4.5 4.5 0 1 1-.008 9h-.006a4.684 4.684 0 0 1-3.12-1.355l-.703.71A5.653 5.653 0 0 0 18.49 23h.011a5.5 5.5 0 0 0 0-11zM11 6.5A1.5 1.5 0 1 1 12.5 8 1.509 1.509 0 0 1 11 6.5zM18.5 20a2.5 2.5 0 1 0-2.447-3h-5.05l-.003.497A4.546 4.546 0 0 1 6.5 22 4.526 4.526 0 0 1 2 17.5a4.596 4.596 0 0 1 3.148-4.37l-.296-.954A5.606 5.606 0 0 0 1 17.5 5.532 5.532 0 0 0 6.5 23a5.573 5.573 0 0 0 5.478-5h4.08a2.487 2.487 0 0 0 2.442 2zm0-4a1.5 1.5 0 1 1-1.5 1.5 1.509 1.509 0 0 1 1.5-1.5z' />
      <path fill='none' d='M0 0h24v24H0z' />
    </svg>`}
/>





## Overview

The Generic Webhook block allows you to receive webhooks from any external service. This is a flexible trigger that can handle any JSON payload, making it ideal for integrating with services that don't have a dedicated Sim block.

## Basic Usage

### Simple Passthrough Mode

Without defining an input format, the webhook passes through the entire request body as-is:

```bash
curl -X POST https://sim.ai/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "X-Sim-Secret: your-secret" \
  -d '{
    "message": "Test webhook trigger",
    "data": {
      "key": "value"
    }
  }'
```

Access the data in downstream blocks using:
- `<webhook1.message>` → "Test webhook trigger"
- `<webhook1.data.key>` → "value"

### Structured Input Format (Optional)

Define an input schema to get typed fields and enable advanced features like file uploads:

**Input Format Configuration:**
```json
[
  { "name": "message", "type": "string" },
  { "name": "priority", "type": "number" },
  { "name": "documents", "type": "files" }
]
```

**Webhook Request:**
```bash
curl -X POST https://sim.ai/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "X-Sim-Secret: your-secret" \
  -d '{
    "message": "Invoice submission",
    "priority": 1,
    "documents": [
      {
        "type": "file",
        "data": "data:application/pdf;base64,JVBERi0xLjQK...",
        "name": "invoice.pdf",
        "mime": "application/pdf"
      }
    ]
  }'
```

## File Uploads

### Supported File Formats

The webhook supports two file input formats:

#### 1. Base64 Encoded Files
For uploading file content directly:

```json
{
  "documents": [
    {
      "type": "file",
      "data": "...",
      "name": "screenshot.png",
      "mime": "image/png"
    }
  ]
}
```

- **Max size**: 20MB per file
- **Format**: Standard data URL with base64 encoding
- **Storage**: Files are uploaded to secure execution storage

#### 2. URL References
For passing existing file URLs:

```json
{
  "documents": [
    {
      "type": "url",
      "data": "https://example.com/files/document.pdf",
      "name": "document.pdf",
      "mime": "application/pdf"
    }
  ]
}
```

### Accessing Files in Downstream Blocks

Files are processed into `UserFile` objects with the following properties:

```typescript
{
  id: string,          // Unique file identifier
  name: string,        // Original filename
  url: string,         // Presigned URL (valid for 5 minutes)
  size: number,        // File size in bytes
  type: string,        // MIME type
  key: string,         // Storage key
  uploadedAt: string,  // ISO timestamp
  expiresAt: string    // ISO timestamp (5 minutes)
}
```

**Access in blocks:**
- `<webhook1.documents[0].url>` → Download URL
- `<webhook1.documents[0].name>` → "invoice.pdf"
- `<webhook1.documents[0].size>` → 524288
- `<webhook1.documents[0].type>` → "application/pdf"

### Complete File Upload Example

```bash
# Create a base64-encoded file
echo "Hello World" | base64
# SGVsbG8gV29ybGQK

# Send webhook with file
curl -X POST https://sim.ai/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "X-Sim-Secret: your-secret" \
  -d '{
    "subject": "Document for review",
    "attachments": [
      {
        "type": "file",
        "data": "data:text/plain;base64,SGVsbG8gV29ybGQK",
        "name": "sample.txt",
        "mime": "text/plain"
      }
    ]
  }'
```

## Authentication

### Configure Authentication (Optional)

In the webhook configuration:
1. Enable "Require Authentication"
2. Set a secret token
3. Choose header type:
   - **Custom Header**: `X-Sim-Secret: your-token`
   - **Authorization Bearer**: `Authorization: Bearer your-token`

### Using Authentication

```bash
# With custom header
curl -X POST https://sim.ai/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "X-Sim-Secret: your-secret-token" \
  -d '{"message": "Authenticated request"}'

# With bearer token
curl -X POST https://sim.ai/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-token" \
  -d '{"message": "Authenticated request"}'
```

## Best Practices

1. **Use Input Format for Structure**: Define an input format when you know the expected schema. This provides:
   - Type validation
   - Better autocomplete in the editor
   - File upload capabilities

2. **Authentication**: Always enable authentication for production webhooks to prevent unauthorized access.

3. **File Size Limits**: Keep files under 20MB. For larger files, use URL references instead.

4. **File Expiration**: Downloaded files have 5-minute expiration URLs. Process them promptly or store them elsewhere if needed longer.

5. **Error Handling**: Webhook processing is asynchronous. Check execution logs for errors.

6. **Testing**: Use the "Test Webhook" button in the editor to validate your configuration before deployment.

## Use Cases

- **Form Submissions**: Receive data from custom forms with file uploads
- **Third-Party Integrations**: Connect with services that send webhooks (Stripe, GitHub, etc.)
- **Document Processing**: Accept documents from external systems for processing
- **Event Notifications**: Receive event data from various sources
- **Custom APIs**: Build custom API endpoints for your applications

## Notes

- Category: `triggers`
- Type: `generic_webhook`
- **File Support**: Available via input format configuration
- **Max File Size**: 20MB per file